home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Aminet 5
/
Aminet 5 - March 1995.iso
/
Aminet
/
dev
/
c
/
simpleguide1.lha
/
simpleguide.c
next >
Wrap
C/C++ Source or Header
|
1995-02-06
|
12KB
|
510 lines
/*
** Support code for easy implementation of the AmigaGuide help system
** in an application. These routines are fully reentrant and
** self-contained. All routines are safe to call even if AmigaGuide
** is not running.
**
** Copyright (C) 1995 Petter Nilsen of Ultima Thule Software,
** All Rights Reserved.
**
*/
#include <libraries/amigaguide.h>
#include <exec/memory.h>
#include <dos/dos.h>
#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/amigaguide.h>
struct GuideContext
{
AMIGAGUIDECONTEXT guidecontext;
ULONG guidesignal;
struct Library *guidebase;
struct ExecBase *SysBase;
};
#define GUIDECONTEXT
typedef struct GuideContext *GuideContext;
#include "simpleguide.h"
/****** simpleguide/AmigaGuideOpen ******************************************
*
* NAME
* AmigaGuideOpen -- Open async AmigaGuide prosess ready for input
*
* SYNOPSIS
* guide = AmigaGuideOpen(nag)
* D0 A0
*
* GuideContext AmigaGuideOpen(struct NewAmigaGuide *);
*
* FUNCTION
* This function will start AmigaGuide async and wait until the help
* system has been successfully started.
* The amigaguide.library V34+ will also be opened.
*
* INPUTS
* nag - a pointer to an initialized NewAmigaGuide structure.
* Unused fields in this structure must be set to 0.
*
* RESULT
* guide - A pointer to a GuideContext, or NULL on failure.
*
* EXAMPLE
*
* enum {
* HELP_MAIN,
* HELP_MACROKEYS,
* };
*
* GuideContext guide = NULL;
*
* struct NewAmigaGuide nag = {NULL};
*
* STRPTR context[] =
* {
* "Main",
* "Macro_Keys", [Note that AmigaGuide won't allow spaces]
* NULL [in a node name!]
* };
*
* nag.nag_BaseName = "THOR Help";
* nag.nag_Name = "THOR.guide"; [Set the document name]
* nag.nag_Screen = Scr; [screen pointer]
* nag.nag_Context = context; [context table]
* nag.nag_Node = HELP_MAIN; [node to align on first]
*
* guide = AmigaGuideOpen(&nag);
*
* [....]
*
* [We need some help here]
*
* if(guide)
* {
* [Set up what node we want help on]
*
* SetGuideContext(guide, HELP_MACROKEYS);
*
* [Start the show]
*
* SendGuideContext(guide);
*
* [Optional: Set the node pointer back to the first node]
*
* SetGuideContext(guide, HELP_MAIN);
* }
*
*
* NOTES
* The AmigaGuide help system must be closed with the AmigaGuideClose()
* function.
* Safe to call with a NULL pointer.
*
* BUGS
*
* SEE ALSO
* AmigaGuideClose, HandleAmigaGuide
*
******************************************************************************
*
*/
__asm GuideContext AmigaGuideOpen(register __a0 struct NewAmigaGuide *nag)
{
struct Library *AmigaGuideBase;
struct AmigaGuideMsg *agm;
GuideContext guide;
BOOL OPEN;
BOOL ACTIVE;
struct ExecBase *SysBase = *(struct ExecBase **)4L;
UBYTE ag_lib[20];
/* We are really serious about having no global data.. :-) */
ag_lib[0] = 'a';
ag_lib[1] = 'm';
ag_lib[2] = 'i';
ag_lib[3] = 'g';
ag_lib[4] = 'a';
ag_lib[5] = 'g';
ag_lib[6] = 'u';
ag_lib[7] = 'i';
ag_lib[8] = 'd';
ag_lib[9] = 'e';
ag_lib[10] = '.';
ag_lib[11] = 'l';
ag_lib[12] = 'i';
ag_lib[13] = 'b';
ag_lib[14] = 'r';
ag_lib[15] = 'a';
ag_lib[16] = 'r';
ag_lib[17] = 'y';
ag_lib[18] = '\0';
if(!nag)
return(NULL);
OPEN = FALSE;
ACTIVE = FALSE;
if(guide = (GuideContext)AllocVec(sizeof(struct GuideContext), MEMF_CLEAR))
{
if(AmigaGuideBase = OpenLibrary(ag_lib, 34L))
{
guide->guidebase = AmigaGuideBase;
guide->SysBase = SysBase;
if(guide->guidecontext = OpenAmigaGuideAsync(nag, NULL))
{
if(guide->guidesignal = AmigaGuideSignal(guide->guidecontext))
{
OPEN = TRUE;
Wait(guide->guidesignal);
while(!ACTIVE)
{
while(agm = GetAmigaGuideMsg(guide->guidecontext))
{
/* Ok startup of the guide file */
if(agm->agm_Type == ActiveToolID)
ACTIVE = TRUE;
/* Opening the guide file failed for some reason, continue as usual */
if(agm->agm_Type == ToolStatusID && agm->agm_Pri_Ret)
ACTIVE = TRUE;
ReplyAmigaGuideMsg(agm);
}
}
}
}
}
if(!OPEN)
{
if(guide)
{
AmigaGuideClose(guide);
guide = NULL;
}
}
}
return(guide);
}
/****** simpleguide/AmigaGuideClose ******************************************
*
* NAME
* AmigaGuideClose -- Close async AmigaGuide prosess already opened with
* AmigaGuideOpen().
*
* SYNOPSIS
* AmigaGuideClose(guide)
* A0
*
* void AmigaGuideClose(GuideContext);
*
* FUNCTION
* This function will close the AmigaGuide async prosess already opened
* with AmigaGuideOpen() and free the structure passed in. If AmigaGuide
* have a window open, this window will be closed. This function should
* used if you close the screen or your application is finished running.
*
* INPUTS
* guide - a pointer to an initialized GuideContext structure optained with
* a call to AmigaGuideOpen().
*
* RESULT
*
* EXAMPLE
*
* NOTES
* Safe to call with a NULL pointer.
*
* BUGS
*
* SEE ALSO
* AmigaGuideOpen, HandleAmigaGuide
*
******************************************************************************
*
*/
__asm void AmigaGuideClose(register __a0 GuideContext guide)
{
struct Library *AmigaGuideBase;
struct ExecBase *SysBase;
if(guide)
{
AmigaGuideBase = guide->guidebase;
SysBase = guide->SysBase;
if(guide->guidecontext)
CloseAmigaGuide(guide->guidecontext);
if(guide->guidebase)
CloseLibrary(guide->guidebase);
FreeVec(guide);
}
}
/****** simpleguide/HandleAmigaGuide ******************************************
*
* NAME
* HandleAmigaGuide - will simple reply to all outstanding messages
* from the AmigaGuide prosess started with
* AmigaGuideOpen().
*
*
* SYNOPSIS
* HandleAmigaGuide(guide)
* A0
*
* void HandleAmigaGuide(GuideContext);
*
* FUNCTION
* This function will simple reply to all outstanding messages from the
* AmigaGuide prosess given with the GuideContext argument.
*
* INPUTS
* guide - a pointer to an initialized GuideContext structure optained with
* a call to AmigaGuideOpen().
*
* RESULT
*
* EXAMPLE
*
* NOTES
* Safe to call with a NULL pointer.
*
* BUGS
*
* SEE ALSO
* AmigaGuideOpen, AmigaGuideClose
*
******************************************************************************
*
*/
__asm void HandleAmigaGuide(register __a0 GuideContext guide)
{
struct Library *AmigaGuideBase;
struct AmigaGuideMsg *agm;
if(guide)
{
AmigaGuideBase = guide->guidebase;
while(agm = GetAmigaGuideMsg(guide->guidecontext))
ReplyAmigaGuideMsg(agm);
}
}
/****** simpleguide.c/GetAmigaGuideSignal ******************************************
*
* NAME
* GetAmigaGuideSignal - will return a signal to be used in event-loops
*
*
* SYNOPSIS
* signal = GetAmigaGuideSignal(guide)
* D0 A0
*
* ULONG GetAmigaGuideSignal(GuideContext);
*
* FUNCTION
* This function will simply return a signal to be used in event loops.
*
* INPUTS
* guide - a pointer to an initialized GuideContext structure optained with
* a call to AmigaGuideOpen().
*
* RESULT
* signal - A signal previously optained in the GuideContext structure
* after calling AmigaGuideOpen(). Will return 0 if the pointer
* passed in is NULL.
*
* EXAMPLE
*
* NOTES
* Safe to call with a NULL pointer, and will return 0L if this is the
* case.
*
* BUGS
*
* SEE ALSO
* AmigaGuideOpen, AmigaGuideClose
*
******************************************************************************
*
*/
__asm ULONG GetAmigaGuideSignal(register __a0 GuideContext guide)
{
if(guide)
return(guide->guidesignal);
else
return(0L);
}
/****** simpleguide/GetAmigaGuideBase ******************************************
*
* NAME
* GetAmigaGuideBase - will return a pointer to AmigaGuideBase
*
* SYNOPSIS
* base = GetAmigaGuideBase(guide)
* D0 A0
*
* struct Library * GetAmigaGuideBase(GuideContext);
*
* FUNCTION
* This function will return a pointer to AmigaGuideBase and must be called
* first if you intent to call any functions in amigaguide.library directly.
*
* INPUTS
* guide - a pointer to an initialized GuideContext structure optained with
* a call to AmigaGuideOpen().
*
* RESULT
* base - A AmigaGuideBase pointer previously optained in the GuideContext
* structure after calling AmigaGuideOpen(). Will return NULL if the
* pointer passed in is NULL.
*
* EXAMPLE
*
* struct Library *AmigaGuideBase;
*
* if(AmigaGuideBase = GetAmigaGuideBase(guidecontext))
* {
* [safely call amigaguide.library functions directly here]
* }
*
* NOTES
* Safe to call with a NULL pointer, and will return NULL if this is the
* case.
*
* BUGS
*
* SEE ALSO
* AmigaGuideOpen, AmigaGuideClose
*
******************************************************************************
*
*/
__asm struct Library *GetAmigaGuideBase(register __a0 GuideContext guide)
{
if(guide)
return(guide->guidebase);
else
return(NULL);
}
/****** simpleguide/SetGuideContext ******************************************
*
* NAME
* SetGuideContext -- Set the context ID for an AmigaGuide system.
*
* SYNOPSIS
* success = SetGuideContext(guide, node)
* D0 A0 D0
*
* BOOL SetGuideContext(GuideContext, ULONG);
*
* FUNCTION
* This function, and the SendGuideContext() function, are used to
* provide a simple way to display a node based on a numeric value,
* instead of having to build up a slightly more complex command
* string.
*
* INPUTS
* guide - a pointer to an initialized GuideContext structure optained with
* a call to AmigaGuideOpen().
*
* node - Index value of the desired node to display.
*
* RESULT
* success - Returns TRUE if a valid context ID and GuideContext pointer was
* passed, otherwise returns FALSE.
*
* EXAMPLE
*
* NOTES
* Safe to call with a NULL pointer, and will return FALSE if this is the
* case.
*
* BUGS
*
* SEE ALSO
* SetAmigaGuideContext, SendGuideContext
*
******************************************************************************
*
*/
__asm BOOL SetGuideContext(register __a0 GuideContext guide, register __d0 ULONG index)
{
struct Library *AmigaGuideBase;
if(guide)
{
AmigaGuideBase = guide->guidebase;
return((BOOL)SetAmigaGuideContext(guide->guidecontext, index, NULL));
}
return(FALSE);
}
/****** simpleguide/SendGuideContext ******************************************
*
* NAME
* SendGuideContext - Align an AmigaGuide system on the context ID.
*
* SYNOPSIS
* success = SendGuideContext(guide)
* D0 A0
*
* BOOL SendGuideContext(GuideContext);
*
* FUNCTION
* This function is used to send a message to an AmigaGuide system to
* align it on the current context ID.
*
* INPUTS
* guide - a pointer to an initialized GuideContext structure optained with
* a call to AmigaGuideOpen().
*
* RESULT
* success - Returns TRUE if a valid GuideContext pointer was passed and the
* message was sent, otherwise returns FALSE.
*
* EXAMPLE
*
* NOTES
* Safe to call with a NULL pointer, and will return FALSE if this is the
* case.
*
* BUGS
*
* SEE ALSO
* SendAmigaGuideContext, SetGuideContext
*
******************************************************************************
*
*/
__asm BOOL SendGuideContext(register __a0 GuideContext guide)
{
struct Library *AmigaGuideBase;
if(guide)
{
AmigaGuideBase = guide->guidebase;
return((BOOL)SendAmigaGuideContext(guide->guidecontext, NULL));
}
return(FALSE);
}